<!DOCTYPE html>
<html>
<head>
<title>XSCHEM TUTORIAL: SYMBOL AND SCHEMATIC GENERATORS</title>
<link rel="stylesheet" type="text/css" href="xschem_man.css" />
<style type="text/css">
/* Local styling goes here */
p{padding: 15px  30px 10px;}
</style>

</head>
<body>

<!-- start of slide -->
<div class="content">   
<!-- navigation buttons -->
<a href="xschem_man.html" class="home">UP</a>

 <!-- slide title -->
 <h1> TUTORIAL: SYMBOL AND SCHEMATIC GENERATORS (aka PCELLS)</h1>
 <p>
  It is possible to insert a symbol by referencing a generator script instead of a <kbd>.sym</kbd> file.
  When inserting the symbol select the <kbd>All</kbd> checkbox to see all files , select the generator script,
  then in the File/Search textbox add two parenthesis <kbd>()</kbd> (or put required parameters in 
  between, like <kbd>(buf,250)</kbd>). If you don't append the <kbd>()</kbd> xschem will do that for you.
 </p>
 <img src="symbol_generators01.png">
 <p>
  The symbolgen.tcl generator in this example takes two parameters,  a <kbd>(buf)</kbd> or a <kbd>(inv)</kbd>
   parameter to generate a buffer or an inverter, respectively, and a output resistance value (a number)
  If no parameters are given (empty parentheses) a buffer is generated with a default ROUT.
<br>
 </p>

 <img src="symbol_generators04.png">


 <p>
  In this example a tcl script is used, you can use any language you like. The script only needs to parse
  the parameters (if any) and outputs on standard output a regular xschem symbol file.
 </p>
 <pre class="code">

#!/bin/sh
# the next line restarts using wish \
exec tclsh "$0" "$@"

set arg1 [lindex $argv 0]
set rout [lindex $argv 1]
# puts stderr "arg1=|$arg1| $rout=|$rout|"
if { $arg1 eq {inv}} {
puts "v {xschem version=3.1.0 file_version=1.2}
K {type=subcircuit
xvhdl_primitive=true
xverilog_primitive=true
xvhdl_format=\"@@y &lt;= not @@a after 90 ps;\"
xverilog_format=\"assign #90 @@y = ~@@a ;\"
format=\"@name @pinlist @symname wn=@wn lln=@lln wp=@wp lp=@lp\"
template=\"name=x1 wn=1u lln=2u wp=4u lp=2u\"
schematic=schematicgen.tcl(inv)}
L 4 -40 0 -20 0 {}
L 4 -20 -20 20 0 {}
L 4 -20 -20 -20 20 {}
L 4 -20 20 20 0 {}
L 4 30 -0 40 -0 {}
B 5 37.5 -2.5 42.5 2.5 {name=y dir=out }
B 5 -42.5 -2.5 -37.5 2.5 {name=a dir=in }
A 4 25 -0 5 180 360 {}
T {$arg1 $rout} -47.5 24 0 0 0.3 0.3 {}
T {@name} 25 -22 0 0 0.2 0.2 {}
T {y} 7.5 -6.5 0 1 0.2 0.2 {}
T {a} -17.5 -6.5 0 0 0.2 0.2 {}
"
} else {
puts "v {xschem version=3.1.0 file_version=1.2}
K {type=subcircuit
xvhdl_primitive=true
xverilog_primitive=true
xvhdl_format=\"@@y &lt;= @@a after 90 ps;\"
xverilog_format=\"assign #90 @@y = @@a ;\"
format=\"@name @pinlist @symname wn=@wn lln=@lln wp=@wp lp=@lp\"
template=\"name=x1 wn=1u lln=2u wp=4u lp=2u\"
schematic=schematicgen.tcl(buf)}
L 4 20 0 40 0 {}
L 4 -40 0 -20 0 {}
L 4 -20 -20 20 0 {}
L 4 -20 -20 -20 20 {}
L 4 -20 20 20 0 {}
B 5 37.5 -2.5 42.5 2.5 {name=y dir=out }
B 5 -42.5 -2.5 -37.5 2.5 {name=a dir=in }
T {$arg1 $rout} -47.5 24 0 0 0.3 0.3 {}
T {@name} 25 -22 0 0 0.2 0.2 {}
T {y} 7.5 -6.5 0 1 0.2 0.2 {}
T {a} -17.5 -6.5 0 0 0.2 0.2 {}
"
}

 </pre>
 <p>
  The <kbd>generators/test_symbolgen.sch</kbd> is a test schematic that places two instances of this
  symbol generator, one as <kbd>symbolgen.tcl(buf,@ROUT\)</kbd> and one as <kbd>symbolgen.tcl(inv,@ROUT\)</kbd>.
  The <kbd>buf,@ROUT</kbd> indicates two parameters, one indicates if it is a buffer or an inverter, 
  the second passes an additional parameter. Instead of using a numeric literal the instance
  value ROUT is passed to the generator.
  A backslash is needed before the closing parenthesis to avoid this parenthesis to be considered
  as part of the parameter.
  The schematic implementations of these symbols are defined by the generator using a <kbd>schematic</kbd>
  attribute. The buffer will use <kbd>schematicgen.tcl(buf)</kbd> and the inverter will
  use <kbd>schematicgen.tcl(inv)</kbd>, these schematic names are referencing a schematic generator
  script instead of regular schematic files.
  You see different schematics (see below picture) when descending the buf or inv generator.
  See next section about schematic generators.
 </p>
 <img src="symbol_generators02.png">
 <p>
  The following is the extracted netlist from this example:
 </p>
 <pre class="code">
** sch_path: /home/schippes/xschem-repo/trunk/xschem_library/generators/test_symbolgen.sch
**.subckt test_symbolgen
x1 IN_INV IN symbolgen_tcl_inv_1200 wn=1u lln=2u wp=4u lp=2u
x3 IN_BUF IN symbolgen_tcl_buf_1200 wn=1u lln=2u wp=4u lp=2u
C1 IN_BUF 0 100f m=1
C2 IN_INV 0 100f m=1
**** begin user architecture code

.include models_rom8k.txt
.param vcc=3
vvcc vcc 0 dc 3
Vin in 0 pwl 0 0 100n 0 100.1n 3 200n 3 200.1n 0
.control
  save all
  tran 1n 300n uic
  write test_symbolgen.raw
.endc


**** end user architecture code
**.ends

* expanding   symbol:  symbolgen.tcl(inv,1200) # of pins=2
** sym_path: /home/schippes/xschem-repo/trunk/xschem_library/generators/symbolgen.tcl
** sch_path: /home/schippes/xschem-repo/trunk/xschem_library/generators/schematicgen.tcl
.subckt symbolgen_tcl_inv_1200 y a  wn=1u lln=2u wp=4u lp=2u
*.opin y
*.ipin a
m2 y a VCC VCC cmosp w=wp l=lp ad='wp *4.6u' as='wp *4.6u' pd='wp *2+9.2u' ps='wp *2+9.2u' m=1
m1 y a 0 0 cmosn w=wn l=lln ad='wn *4.3u' as='wn *4.3u' pd='wn *2+8.6u' ps='wn *2+8.6u' m=1
.ends


* expanding   symbol:  symbolgen.tcl(buf,1200) # of pins=2
** sym_path: /home/schippes/xschem-repo/trunk/xschem_library/generators/symbolgen.tcl
** sch_path: /home/schippes/xschem-repo/trunk/xschem_library/generators/schematicgen.tcl
.subckt symbolgen_tcl_buf_1200 y a  wn=1u lln=2u wp=4u lp=2u
*.opin y
*.ipin a
m2 net1 a VCC VCC cmosp w=wp l=lp ad='wp *4.6u' as='wp *4.6u' pd='wp *2+9.2u' ps='wp *2+9.2u' m=1
m1 net1 a 0 0 cmosn w=wn l=lln ad='wn *4.3u' as='wn *4.3u' pd='wn *2+8.6u' ps='wn *2+8.6u' m=1
m3 y net1 VCC VCC cmosp w=wp l=lp ad='wp *4.6u' as='wp *4.6u' pd='wp *2+9.2u' ps='wp *2+9.2u' m=1
m4 y net1 0 0 cmosn w=wn l=lln ad='wn *4.3u' as='wn *4.3u' pd='wn *2+8.6u' ps='wn *2+8.6u' m=1
.ends

.end

 </pre>
 <p>
  This approach allows to create polymorphic symbols. Multiple parameters may be given to the generator script,
  like <kbd>symbolgen.tcl(inv,hv,100)</kbd>. Xschem will call the symbolgen.tcl script with the following command:
  <kbd>symbolgen.tcl inv hv 100</kbd> and take the standard output from the script as the symbol
  file to load and display.
 </p>
 <h2> Schematic generators (pcells)</h2>
 <p>
  The same approach used for symbol generators can be used for schematic generators. If you add a 
  <kbd>schematic=schematicgen.tcl(buf,4)</kbd> attribute to an instance
  xschem will look for a script named <kbd>schematicgeni.tcl</kbd> in the search paths and call
  it with the given parameters (that is, execute the command 
  <kbd>schematicgen.tcl buf 4</kbd>) and read the produced output as a schematic file.
 </p>
 <img src="symbol_generators03.png">
 <br><br><br>
 <!-- end of slide -->
 <div class="filler"></div>
</div>

<!-- frame footer -->
<iframe seamless src="xschem_footer.html"  class="footer_iframe" >
</body>
</html>

